Constants

ERROR_READ_ONLY

ERROR_READ_ONLY = 1

ERROR_NO_CONNECTION

ERROR_NO_CONNECTION = 2

ERROR_VALIDATE

ERROR_VALIDATE = 3

ERROR_SAVING

ERROR_SAVING = 4

SEARCH_ALL

SEARCH_ALL = 0

SEARCH_STRICT

SEARCH_STRICT = 1

SEARCH_PREFIX

SEARCH_PREFIX = 2

SEARCH_GROUPS

SEARCH_GROUPS = 4

TYPE_CONTACT

TYPE_CONTACT = 0

TYPE_RECIPIENT

TYPE_RECIPIENT = 1

TYPE_TRUSTED_SENDER

TYPE_TRUSTED_SENDER = 2

TYPE_DEFAULT

TYPE_DEFAULT = 4

TYPE_WRITEABLE

TYPE_WRITEABLE = 8

TYPE_READONLY

TYPE_READONLY = 16

Properties

$primary_key

$primary_key : string

Type

string — Name of the primary key field of this addressbook. Used to search for previously retrieved IDs.

$groups

$groups : bool

Type

bool — True if the addressbook supports contact groups.

$export_groups

$export_groups : bool

Type

bool — True if the addressbook supports exporting contact groups. Requires the implementation of get_record_groups().

$readonly

$readonly : bool

Type

bool — True if the addressbook is read-only.

$searchonly

$searchonly : bool

Type

bool — True if the addressbook does not support listing all records but needs use of the search function.

$undelete

$undelete : bool

Type

bool — True if the addressbook supports restoring deleted contacts.

$ready

$ready : bool

Type

bool — True if the addressbook is ready to be used. See rcmail_action_contacts_index::$CONTACT_COLTYPES

$group_id

$group_id : null|string|int

Type

null|string|int — If set, addressbook-specific identifier of the selected group. All contact listing and contact searches will be limited to contacts that belong to this group.

$list_page

$list_page : int

Type

int — The current page of the listing. Numbering starts at 1.

$page_size

$page_size : int

Type

int — The maximum number of records shown on a page.

$sort_col

$sort_col : string

Type

string — Contact field by which to order listed records.

$sort_order

$sort_order : string

Type

string — Whether sorting of records by $sort_col is done in ascending (ASC) or descending (DESC) order.

$date_cols

$date_cols : string[]

Type

string[] — A list of record fields that contain dates.

$coltypes

$coltypes : array

Type

array — Definition of the contact fields supported by the addressbook.

$vcard_map

$vcard_map : string[]

Type

string[] — vCard additional fields mapping

$error

$error : ?array

Type

?array — Error state - hash array with the following fields: type, message

Methods

get_name()

get_name() : string

Returns addressbook name (e.g. for addressbooks listing)

Returns

string —

set_search_set()

set_search_set(mixed  $filter) : void

Sets a search filter.

This affects the contact set considered when using the count() and list_records() operations to those contacts that match the filter conditions. If no search filter is set, all contacts in the addressbook are considered.

This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.

Parameters

mixed $filter

Search params to use in listing method, obtained by get_search_set()

get_search_set()

get_search_set() : mixed

Getter for saved search properties.

The filter representation is opaque to roundcube, but can be set again using set_search_set().

Returns

mixed —

Search properties used by this class

reset()

reset() : void

Reset saved results and search parameters

refresh_search()

refresh_search() : mixed

Refresh saved search set after data has changed

Returns

mixed —

New search set

list_records()

list_records(?array  $cols = null, int  $subset, bool  $nocount = false) : \rcube_result_set

Lists the current set of contact records.

See the description of count() for the criteria determining which contacts are considered for the listing.

The actual records returned may be fewer, as only the records for the current page are returned. The returned records may be further limited by the $subset parameter, which means that only the first or last $subset records of the page are returned, depending on whether $subset is positive or negative. If $subset is 0, all records of the page are returned. The returned records are found in the $records property of the returned result set.

Finally, the $first property of the returned result set contains the index into the total set of filtered records (i.e. not considering the segmentation into pages) of the first returned record before applying the $subset parameter (i.e., $first is always a multiple of the page size).

The $nocount parameter is an optimization that allows to skip querying the total amount of records of the filtered set if the caller is only interested in the records. In this case, the $count property of the returned result set will simply contain the number of returned records, but the filtered set may contain more records than this.

The result of the operation is internally cached for later retrieval using get_result().

Parameters

?array $cols

List of columns to include in the returned records (null means all)

int $subset

Only return this number of records of the current page, use negative values for tail

bool $nocount

True to skip the count query (select only)

Returns

\rcube_result_set —

Indexed list of contact records, each a hash array

search()

search(string|string[]  $fields, string|string[]  $value, int  $mode, bool  $select = true, bool  $nocount = false, string|string[]  $required = []) : \rcube_result_set

Search records

Depending on the given parameters the search() function operates in different ways (in the order listed):

"Direct ID search" - when $fields is either 'ID' or $this->primary_key - $values is either a string of contact IDs separated by self::SEPARATOR (,) or an array of contact IDs - Any contact with one of the given IDs is returned

"Advanced search" - when $value is an array - Each value in $values is the search value for the field in $fields at the same index - All fields must match their value to be included in the result ("AND" semantics)

"Search all fields" - when $fields is '*' (note: $value is a single string) - Any field must match the value to be included in the result ("OR" semantics)

"Search given fields" - if none of the above matches - Any of the given fields must match the value to be included in the result ("OR" semantics)

All matching is done case insensitive.

The search settings are remembered (see set_search_set()) until reset using the reset() function. They can be retrieved using get_search_set(). The remembered search settings must be considered by list_records() and count().

The search mode can be set by the admin via the config.inc.php setting addressbook_search_mode. It is used as a bit mask, but the search modes are exclusive (SEARCH_GROUPS is combined with one of other modes): SEARCH_ALL: substring search (abc) SEARCH_STRICT: Exact match search (case insensitive =) SEARCH_PREFIX: Prefix search (abc*) SEARCH_GROUPS: include groups in search results (if supported)

When records are requested in the returned rcube_result_set ($select is true), the results will only include the contacts of the current page (see list_page, page_size). The behavior is as described with the list_records function, and search() can be thought of as a sequence of set_search_set() and list_records() under that filter.

If $nocount is true, the count property of the returned rcube_result_set will contain the amount of records contained within that set. Calling search() with $select=false and $nocount=true is not a meaningful use case and will result in an empty result set without records and a count property of 0, which gives no indication on the actual record set matching the given filter.

The result of the operation is internally cached for later retrieval using get_result().

Parameters

string|string[] $fields

Field names to search in

string|string[] $value

Search value, or array of values, one for each field in $fields

int $mode

Search mode. Sum of rcube_addressbook::SEARCH_*.

bool $select

True if records are requested in the result, false if count only

bool $nocount

True to skip the count query (select only)

string|string[] $required

Field or list of fields that cannot be empty

Returns

\rcube_result_set —

Contact records and 'count' value

count()

count() : \rcube_result_set

Count the number of contacts in the database matching the current filter criteria.

The current filter criteria are defined by the search filter (see search()/set_search_set()) and the currently active group (see set_group()), if applicable.

Returns

\rcube_result_set —

Result set with values for 'count' and 'first'

get_result()

get_result() : ?\rcube_result_set

Return the last result set

Returns

?\rcube_result_set —

Current result set or NULL if nothing selected yet

get_record()

get_record(mixed  $id, bool  $assoc = false) : \rcube_result_set|array

Get a specific contact record

Parameters

mixed $id

Record identifier(s)

bool $assoc

True to return record as associative array, otherwise a result set is returned

Returns

\rcube_result_set|array —

Result object with all record fields

get_error()

get_error() : ?array

Returns the last error occurred (e.g. when updating/inserting failed)

Returns

?array —

Hash array with the following fields: type, message. Null if no error set.

close()

close() : mixed

Close connection to source Called on script shutdown

Returns

mixed —

set_page()

set_page(int  $page) : mixed

Set internal list page

Parameters

int $page

Page number to list

Returns

mixed —

set_pagesize()

set_pagesize(int  $size) : mixed

Set internal page size

Parameters

int $size

Number of messages to display on one page

Returns

mixed —

set_sort_order()

set_sort_order(?string  $sort_col, ?string  $sort_order = null) : mixed

Set internal sort settings

Parameters

?string $sort_col

Sort column

?string $sort_order

Sort order

Returns

mixed —

validate()

validate(array  $save_data, bool  $autofix = false) : bool

Check the given data before saving.

If input isn't valid, the message to display can be fetched using get_error()

Parameters

array $save_data

Associative array with data to save

bool $autofix

Attempt to fix/complete record automatically

Returns

bool —

True if input is valid, False if not.

insert()

insert(array  $save_data, bool  $check = false) : mixed

Create a new contact record

Parameters

array $save_data

Associative array with save data Keys: Field name with optional section in the form FIELD:SECTION Values: Field value. Can be either a string or an array of strings for multiple values

bool $check

True to check for duplicates first

Returns

mixed —

The created record ID on success, False on error

insertMultiple()

insertMultiple(\rcube_result_set  $recset, bool  $check = false) : array

Create new contact records for every item in the record set

Parameters

\rcube_result_set $recset

Recordset to insert

bool $check

True to check for duplicates first

Returns

array —

List of created record IDs

update()

update(mixed  $id, array  $save_cols) : mixed

Update a specific contact record

Parameters

mixed $id

Record identifier

array $save_cols

Associative array with save data Keys: Field name with optional section in the form FIELD:SECTION Values: Field value. Can be either a string or an array of strings for multiple values

Returns

mixed —

On success if ID has been changed returns ID, otherwise True, False on error

delete()

delete(array  $ids, bool  $force = true) : int|false

Mark one or more contact records as deleted

Parameters

array $ids

Record identifiers

bool $force

Remove records irreversible (see self::undelete)

Returns

int|false —

Number of removed records, False on failure

undelete()

undelete(array  $ids) : mixed

Unmark delete flag on contact record(s)

Parameters

array $ids

Record identifiers

Returns

mixed —

delete_all()

delete_all(bool  $with_groups = false) : mixed

Mark all records in database as deleted

Parameters

bool $with_groups

Remove also groups

Returns

mixed —

set_group()

set_group(mixed  $group_id) : mixed

Sets/clears the current group.

This affects the contact set considered when using the count(), list_records() and search() operations to those contacts that belong to the given group. If no current group is set, all contacts in the addressbook are considered.

This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.

Parameters

mixed $group_id

Returns

mixed —

list_groups()

list_groups(?string  $search = null, int  $mode) : array

List all active contact groups of this source

Parameters

?string $search

Optional search string to match group name

int $mode

Search mode. Sum of self::SEARCH_*

Returns

array —

Indexed list of contact groups, each a hash array

get_group()

get_group(string  $group_id) : ?array

Get group properties such as name and email address(es)

Parameters

string $group_id

Group identifier

Returns

?array —

Group properties as hash array, null in case of error.

create_group()

create_group(string  $name) : array|false

Create a contact group with the given name

Parameters

string $name

The group name

Returns

array|false —

False on error, array with record props in success

delete_group()

delete_group(string  $group_id) : bool

Delete the given group and all linked group members

Parameters

string $group_id

Group identifier

Returns

bool —

True on success, false if no data was changed

rename_group()

rename_group(string  $group_id, string  $newname, string  $newid) : string|false

Rename a specific contact group

Parameters

string $group_id

Group identifier

string $newname

New name to set for this group

string $newid

New group identifier (if changed, otherwise don't set)

Returns

string|false —

New name on success, false if no data was changed

add_to_group()

add_to_group(string  $group_id, array|string  $ids) : int

Add the given contact records the a certain group

Parameters

string $group_id

Group identifier

array|string $ids

List of contact identifiers to be added

Returns

int —

Number of contacts added

remove_from_group()

remove_from_group(string  $group_id, array|string  $ids) : int

Remove the given contact records from a certain group

Parameters

string $group_id

Group identifier

array|string $ids

List of contact identifiers to be removed

Returns

int —

Number of deleted group members

get_record_groups()

get_record_groups(mixed  $id) : array

Get group assignments of a specific contact record

Parameters

mixed $id

Record identifier

Returns

array —

List of assigned groups indexed by a group ID. Every array element can be just a group name (string), or an array with 'ID' and 'name' elements.

get_col_values()

get_col_values(string  $col, array  $data, bool  $flat = false) : array

Utility function to return all values of a certain data column either as flat list or grouped by subtype

Parameters

string $col

Col name

array $data

Record data array as used for saving

bool $flat

True to return one array with all values, False for hash array with values grouped by type

Returns

array —

List of column values

compose_display_name()

compose_display_name(array  $contact, bool  $full_email = false) : string

Compose a valid display name from the given structured contact data

Parameters

array $contact

Hash array with contact data as key-value pairs

bool $full_email

Don't attempt to extract components from the email address

Returns

string —

Display name

compose_list_name()

compose_list_name(array  $contact) : string

Compose the name to display in the contacts list for the given contact record.

This respects the settings parameter how to list contacts.

Parameters

array $contact

Hash array with contact data as key-value pairs

Returns

string —

List name

compose_search_name()

compose_search_name(array  $contact, string  $email = null, string  $name = null, string  $templ = null) : string

Build contact display name for autocomplete listing

Parameters

array $contact

Hash array with contact data as key-value pairs

string $email

Optional email address

string $name

Optional name (self::compose_list_name() result)

string $templ

Optional template to use (defaults to the 'contact_search_name' config option)

Returns

string —

Display name

compose_contact_key()

compose_contact_key(array  $contact, string  $sort_col) : string

Create a unique key for sorting contacts

Parameters

array $contact

Contact record

string $sort_col

Sorting column name

Returns

string —

Unique key

set_error()

set_error(int  $type, string  $message) : mixed

Setter for errors for internal use

Parameters

int $type

Error type (one of this class' error constants)

string $message

Error message (name of a text label)

Returns

mixed —

compare_search_value()

compare_search_value(string  $colname, string|array  $value, string  $search, int  $mode) : bool

Compare search value with contact data

Parameters

string $colname

Data name

string|array $value

Data value

string $search

Search value

int $mode

Search mode

Returns

bool —

Comparison result